<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Mode analysis
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot091.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot083.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc216">15.9</A>&nbsp;&nbsp;Mode analysis</H2>
The mode_analyser library is a tool that assists in the generation 
of the mode/1 directive for predicate definitions. This directive informs 
the compiler that the arguments of the specified predicate will always 
have the corresponding form when the predicate is called. The compiler 
utilises this information during compilation of the predicate in order 
to generate more compact and/or faster code. Specifying the mode of a 
predicate that has already been compiled has no effect, unless it is 
recompiled. If the specified procedure does not exist, a local undefined 
procedure is created.<BR>
<BR>
The mode analyser inserts instrumentation into the clause definitions 
of predicates during compilation in order to record mode usage of each 
predicate argument. The code should then be run (as many times as is 
necessary to capture the most common invocations of each predicate 
undergoing analysis). Finally, the results of the analysis are requested
and the suggested mode annotations for each predicate are displayed.<BR>
<BR>
The usage is as follows: 
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
Load the mode_analyser library:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- lib(mode_analyser).
</PRE></BLOCKQUOTE>
<LI CLASS="li-enumerate">Compile your program with the mode analyser:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- analyse(queen).
</PRE></BLOCKQUOTE>
<LI CLASS="li-enumerate">Run the query which most accurately exercises the 
invocation modes of the defined predicates: 
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- queen:queen([1,2,3,4],Out).
</PRE></BLOCKQUOTE>
<LI CLASS="li-enumerate">Generate the results for the module into which 
the program was compiled:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- result([verbose:on])@queen.
</PRE></BLOCKQUOTE>
</OL>
This will print the results as follows:
<PRE CLASS="verbatim">
Mode analysis for queen : qdelete / 4:
        Results for argument 1:
                -: 23   *: 0    +: 0    ++: 0
        Results for argument 2:
                -: 0    *: 0    +: 0    ++: 23
        Results for argument 3:
                -: 0    *: 0    +: 0    ++: 23
        Results for argument 4:
                -: 0    *: 0    +: 23   ++: 0

        qdelete(-, ++, ++, +)

Mode analysis for queen : nodiag / 3:
        Results for argument 1:
                -: 0    *: 0    +: 0    ++: 62
        Results for argument 2:
                -: 0    *: 0    +: 0    ++: 62
        Results for argument 3:
                -: 0    *: 0    +: 0    ++: 62

        nodiag(++, ++, ++)

Mode analysis for queen : qperm / 2:
        Results for argument 1:
                -: 0    *: 0    +: 0    ++: 41
        Results for argument 2:
                -: 0    *: 0    +: 41   ++: 0

        qperm(++, +)

Mode analysis for queen : queen / 2:
        Results for argument 1:
                -: 0    *: 0    +: 0    ++: 1
        Results for argument 2:
                -: 1    *: 0    +: 0    ++: 0

        queen(++, -)

Mode analysis for queen : safe / 1:
        Results for argument 1:
                -: 0    *: 0    +: 0    ++: 38

        safe(++)
</PRE>
NOTE: It is imperative to understand that the results of mode analysis
are merely suggestions for the invocation modes of a predicate based on
runtime information. If there are potential predicate invocation modes
that were not exercised during runtime, the tool is unable to account
for them in its analysis. For the mode specifier '-' the mode analyser
does not determine whether the variable occurs in any other argument
(i.e. is aliased), this must be manually verified.
In summary, the programmer must verify that the suggested modes are correct
before using the directive in the code. If the instantiation of the
predicate call violates its mode declaration, no exception is raised and
its behaviour is undefined.<BR>
<BR>
For more details about invocation mode analysis see 
the <A HREF="../bips/lib/mode_analyser/index.html"><B>Reference Manual</B></A><A NAME="@default896"></A>.<BR>
<BR>
<HR>
<A HREF="umsroot091.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot083.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
